属性的命名

注: 以下做法只是为了尽量避免和 QML 内置属性重命, 以及为了更方便开发者通过名字就能确定它的一些特征.

id 属性使用 "_xxx" 作为前缀, 并仅限于当前 qml 文件的引用

_xxx 下划线开头的变量用于暗示这是一个 "私有" 变量, 请避免让它被外部文件直接访问.

xxxxxxxxxx
1
// === A.qml ===
2
import QtQuick 2.15
3
​
4
Item {
5
    property alias p_size: _txt.font.pixelSize
6
    property alias p_text: _txt.text
7
    Text { id: _txt }
8
}
9
​
10
// === B.qml ===
11
import QtQuick 2.15
12
​
13
Item {
14
    A {
15
        // 在 B.qml 中, 是访问不到 A.qml 的 id 为 _txt 的对象的. 这也是我们希望
16
        //  看到的结果.
17
        // 不过我们可以访问和修改 p_size 和 p_text.
18
        p_size: 18
19
        p_text: "hello world"
20
    }
21
}
22
​

property 定义的 "public" 变量使用 "p_xxx" 作为前缀

xxxxxxxxxx
6
1
import QtQuick 2.15
2
​
3
Item {
4
    property string p_text: ""
5
    Text { text: p_text }
6
}

property 定义的 "private" 变量使用 "__xxx" 作为前缀

x
1
import QtQuick 2.15
2
​
3
Item {
4
    property bool __active: false  // `__active` 只允许在该文件内使用, 请不要在
5
    //  外部调用时修改它.
6
    
7
    Rectangle {
8
        color: __active ? "white" : "gray"
9
        width: 100; height: 100
10
        
11
        MouseArea {
12
            anchors.fill: parent
13
            onClicked: {
14
                __active = !__active
15
            }
16
        }
17
    }
18
}
19
​

objectName 属性使用 "{相对路径}#{id}" 的形式, 其中 id 必须被先声明

xxxxxxxxxx
1
// === D:/workspace/my_prj/ui/page1/Element.qml ===
2
import QtQuick 2.15
3
​
4
Item {
5
    id: _root
6
    // 相对路径是相对于当前项目 (my_prj) 的路径.
7
    objectName: "ui/page1/Element.qml#_root"  
8
    
9
    Text {
10
        id: _txt 
11
        objectName: "ui/page1/Element.qml#_txt"
12
        text: ""
13
    }
14
}

property 优先使用 alias 变量

xxxxxxxxxx
17
1
// === A.qml ===
2
import QtQuick 2.15
3
​
4
Item {
5
    // 推荐
6
    property alias p_text1: _txt1.text  
7
    Text {
8
        id: _txt1
9
    }
10
    
11
    // 不推荐
12
    property string p_text2: ""  
13
    Text { 
14
        id: _txt2
15
        text: p_text2
16
    }
17
}
18
​

property 定义的 alias 变量, 如果引用的是对象的 id, 则用 "obj_Xxx" 作为前缀, 且使用大驼峰式写法

x
1
// === A.qml ===
2
import QtQuick 2.15
3
​
4
Item {
5
    property alias obj_Text: _txt
6
    
7
    Text { 
8
        id: _txt
9
    }
10
}
11
​
12
// === B.qml ===
13
import QtQuick 2.15
14
​
15
Item {
16
    A {
17
        p_text: "hello world"
18
        
19
        // 在 B.qml 中, 不能直接访问 A.qml 的 id 为 _txt 的对象, 但可以通过 
20
        //  obj_Text 访问到它.
21
        obj_Text {  // 这里相当于引用了 A.Item.Text 对象.
22
            font.bold: true
23
        }
24
    }
25
}
26
​

函数和信号使用 "fn_xxx" 作为前缀

xxxxxxxxxx
38
1
// === A.qml ===
2
import QtQuick 2.15
3
​
4
Rectangle {
5
    id: _rect
6
    color: "white"
7
    width: 100; height: 100
8
    
9
    signal fn_clicked(string color)
10
    
11
    MouseArea {
12
        onClicked: {
13
            fn_clicked(_rect.color)
14
        }
15
    }
16
}
17
​
18
// === B.qml ===
19
import QtQuick 2.15
20
​
21
Item {
22
    width: 500; height: 500
23
    
24
    function fn_showColor(color) {
25
        _txt.text = color  // 当点击 A 对象, 会使 _txt 对象的文字显示为 A 的颜色.
26
    }
27
    
28
    A { 
29
        fn_clicked.connect(fn_showColor)
30
    }
31
    
32
    Text {
33
        id: _txt
34
        anchors.centerIn: parent
35
        text: "what's the color?"
36
    }
37
}
38
​

属性的书写顺序

1. id 始终位于第一行, objectName 始终位于第二行

   xxxxxxxxxx
   1
   import QtQuick 2.15
   2
   ​
   3
   Text {
   4
       id: _txt
   5
       objectName: "my_txt"
   6
   }
   

2. 以下属性按照指定顺序置顶显示: id > objectName > name > source (常见于 Loader 对象) > target (常见于 State 对象) > 其他内建属性 (按照字母表顺序) > 自定义属性 (按照字母表顺序).

   x
   1
   import QtQuick 2.15
   2
   ​
   3
   Rectangle {
   4
       id: _root
   5
       objectName: "my_item"
   6
       anchors.left: parent
   7
       anchors.margins: 12
   8
       anchors.top: parent
   9
       
   10
       property bool p_active: false
   11
       
   12
       states: [
   13
           State {
   14
               name: "defaultState"
   15
               when: p_active
   16
               PropertyChanges {
   17
                   target: _root
   18
                   color: "white"
   19
                   x: 10
   20
                   y: 10
   21
               }
   22
           }
   23
       ]
   24
       
   25
       Loader {
   26
           id: _item1
   27
           source: "./Items/Item1.qml"
   28
           anchors.centerIn: parent
   29
       }
   30
   }
   31
   ​
   

3. 对于关联性强的元素, 可以合并到一行书写 (在单行内的属性书写顺序无需按照字母表顺序)

   x
   1
   import QtQuick 2.15
   2
   ​
   3
   Rectangle {
   4
       id: _rect
   5
       color: "#FAFAFA"
   6
       width: 100; height: 100  // 并到了一行书写.
   7
       x: 10; y: 10; z: 1  // 并到了一行书写.
   8
       
   9
       property alias p_color: _rect.color
   10
       property int p_index: 0
   11
       property string p_text: ""
   12
       signal fn_clicked(string color)
   13
       
   14
       Text {
   15
           id: _txt
   16
           anchors.centerIn: parent
   17
           text: p_text
   18
           
   19
           font.bold: true
   20
           font.family: "Microsoft YaHei UI"
   21
           font.pixelSize: 18
   22
       }
   23
   }
   

视图/模型分离的设计

原则: QML 只负责布局和 UI 的呈现, 模型 (数据) 以及模型交互的逻辑全部由 Python 实现.

实践类问题: 我在 QML 中有一个 Grid 对象, 我想要通过 Python 向里面动态地添加 MyItem 对象, 我该怎么做?

具体的实现讲解见这篇文章: TODO. 这里从设计原则的角度说一下应该怎么做.

首先, 这个思路是不可取的: Python 通过 engine 获取到 Grid 对象, 并操作 Grid 的 add 方法, 渲染并插入一个 MyItem 对象.

这个思路的问题有两个:

1. 经我个人实验, "操作 Grid 的 add 方法" 这一步似乎无法在 Python 中实现, Qt 没有提供此方法, 网上也找不到解答
2. 这不符合视图/模型分离的设计原则, 我们在 Python 中操作 Grid, 为其插入 MyItem, 这个工作属于 UI 操作范畴, 本应该交由 QML 引擎实现. 所以正确的做法是我们 Python 只操作 Grid 的数据模型, 使模型中新增一个 MyItem 的数据, 然后 QML 根据模型变动在布局中渲染出一个 MyItem

所以, 一个可参考的思路是这样的:

QML 端: Grid 内套一个 Repeater 对象 (因为 Repeater 有 model 属性), Repeater 的 delegate 属性 (代理对象) 设为 MyItem

Python 端: Python 通过 engine 获取到 Repeater 对象, 对其 model 进行操作, 插入一条 MyItem 的数据. QML 自动完成 UI 的更新.